.\" -*- nroff -*-
.TH STAPRUN 8 
.SH NAME
staprun \- systemtap runtime

.SH SYNOPSIS

.br
.B staprun
[
.I OPTIONS
]
.I MODULE
[
.I MODULE-OPTIONS
]

.SH DESCRIPTION

The
.I staprun
program is the back-end of the Systemtap tool.  It expects a kernel
module produced by the front-end
.I stap
tool.
.PP
Splitting the systemtap tool into a front-end and a back-end allows a
user to compile a systemtap script on a development machine that has
the kernel development tools (needed to compile the script) and then
transfer the resulting kernel module to a production machine that
doesn't have any development tools installed.
.PP
Please refer to stappaths (7) for the version number, or run
rpm \-q systemtap (fedora/red hat)
apt\-get \-v systemtap (ubuntu)

.SH OPTIONS
The
.I staprun
program supports the following options.  Any other option
prints a list of supported options.
.TP
.B \-v
Verbose mode. The level of verbosity is also set in the
.I SYSTEMTAP_VERBOSE
environment variable.
.TP
.B \-V
Print version number and exit.
.TP
.B \-w
Suppress warnings from the script.
.TP
.B \-u
Load the uprobes.ko module.
.TP
.B \-c CMD
Command CMD will be run and the
.I staprun
program will exit when CMD
does.  The '_stp_target' variable will contain the pid for CMD.
.TP
.B \-x PID
The '_stp_target' variable will be set to PID.
.TP
.B \-N PID
Sets the '_stp_namespaces_pid' variable to PID.
.TP
.B \-o FILE
Send output to FILE. If the module uses bulk mode, the output will
be in percpu files FILE_x(FILE_cpux in background and bulk mode)
where 'x' is the cpu number. This supports strftime(3) formats
for FILE.
.TP
.B \-b BUFFER_SIZE
The systemtap module will specify a buffer size.
Setting one here will override that value. The value should be
an integer between 1 and 4095 which be assumed to be the
buffer size in MB. That value will be per-cpu if bulk mode is used.
.TP
.B \-L
Load module and start probes, then detach from the module leaving the
probes running.  The module can be attached to later by using the
.B \-A
option.
.TP
.B \-A
Attach to loaded systemtap module.
.TP
.B \-C WHEN
Control coloring of error messages. WHEN must be either
.nh
"never", "always", or "auto"
.hy
(i.e. enable only if at a terminal). If the option is missing, then "auto"
is assumed. Colors can be modified using the SYSTEMTAP_COLORS environment
variable. See the
.IR stap (1)
manual page for more information on syntax and behaviour.
.TP
.B \-M INTERVAL
Enable monitor mode with INTERVAL seconds between updates.
.TP
.B \-d
Delete a module.  Only detached or unused modules
the user has permission to access will be deleted. Use "*"
(quoted) to delete all unused modules.
.TP
.BI \-D
Run staprun in background as a daemon and show it's pid.
.TP
.B \-R
Rename the module to a unique name before inserting it.
.TP
.B \-r N:URI
Pass the given number and URI data to the tapset functions
remote_id() and remote_uri().
.TP
.BI \-S " size[,N]"
Sets the maximum size of output file and the maximum number of output files.
If the size of output file will exceed
.B size
megabytes, systemtap switches output file to the next file. And if the number of
output files exceed
.B N
, systemtap removes the oldest output file. You can omit the second argument.
.TP
.B \-T timeout
Sets maximum time reader thread will wait before dumping trace buffer. Value is
in ms, default is 200ms. Setting this to a high value decreases number of stapio
wake-ups, allowing deeper sleep for embedded platforms. But it impacts interactivity
on terminal as traces are dumped less often in case of low throughput.
There is no interactivity or performance impact for high throughput as trace is
dumped when buffer is full, before this timeout expires.
.TP
.B var1=val
Sets the value of global variable var1 to val. Global variables contained 
within a module are treated as module options and can be set from the 
staprun command line.

.SH ARGUMENTS
.B MODULE
is either a module path or a module name.  If it is a module name,
the module will be looked for in the following directory
(where 'VERSION' is the output of "uname \-r"):
.IP
/lib/modules/VERSION/systemtap
.PP
.\" TODO - we probably need a better description here.
Any additional arguments on the command line are passed to the
module.  One use of these additional module arguments is to set the value 
of global variables declared within the module.
.PP

\& $ stap \-p4 \-m mod1 \-e\ \[aq]global var1="foo"; probe begin{printf("%s\\n", var1); exit()}\[aq]
.br
.PP
Running this with an additional module argument:
.PP

\& $ staprun mod1.ko var1="HelloWorld"
.br
\& HelloWorld
.PP
Spaces and exclamation marks currently cannot be passed into global variables 
this way.

.SH EXAMPLES
See the 
.IR stapex (3stap)
manual page for a collection of sample scripts.
.PP
Here is a very basic example of how to use
.I staprun.
First, use
.I stap
to compile a script.  The
.I stap
program will report the pathname to the resulting module.
.PP
\& $ stap \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
.PP
Run
.I staprun
with the pathname to the module as an argument.
.PP
\& $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
.br
\& Hello World!
.SH MODULE DETACHING AND ATTACHING
After the
.I staprun
program installs a Systemtap kernel module, users can detach from the
kernel module and reattach to it later.  The
.B \-L
option loads the module and automatically detaches.  Users can also
detach from the kernel module interactively by sending the SIGQUIT
signal from the keyboard (typically by typing Ctrl\-\\).
.PP
To reattach to a kernel module, the
.I staprun
.B \-A
option would be used.

.SH FILE SWITCHING BY SIGNAL
After
.I staprun
launched the
.I stapio
program, users can command it to switch output file to next file when it
outputs to file(s) (running staprun with
.B \-o
option) by sending a
.B SIGUSR2
signal to the
.I stapio
process. When it receives SIGUSR2, it will switch output file to
new file with suffix 
.I .N
where N is the sequential number.
For example,
.PP
\& $ staprun \-o foo ...
.PP
outputs trace logs to 
.I foo
and if it receives
.B SIGUSR2
signal, it switches output to
.I foo.1
file. And receiving
.B SIGUSR2
again, it switches to 
.I foo.2
file.

.SH SAFETY AND SECURITY
Systemtap, in the default kernel-module runtime mode, is an
administrative tool.  It exposes kernel internal data structures and
potentially private user information.  See the
.IR stap (1)
manual page for additional information on safety and security.
.PP
To increase system security, users of systemtap must be root, or in the
.I stapusr
group in order to execute this setuid 
.I staprun
program.
A user may select a particular privilege level with the stap
.I \-\-privilege=
option, which 
.I staprun
will later enforce.
.TP
stapdev
Members of the
.I stapdev
group can write and load script modules with root-equivalent
privileges, without particular security constraints.  (Many safety
constraints remain.)
.TP
stapsys
Members of the
.I stapsys
group have almost all the privileges of 
.IR stapdev ,
except for guru mode constructs.
.TP
stapusr
Members only of the
.I stapusr
group may any-privileged modules placed into the /lib/modules/VERSION/systemtap 
by the system administrator.
.TP
stapusr
Members only of the
.I stapusr
group may also write and load low-privilege script modules, which are normally
limited to manipulating their own processes (and not the kernel nor other users'
processes).
.PP
Part of the privilege enforcement mechanism may require using a 
stap-server and administrative trust in its cryptographic signer; see the
.IR stap\-server (8)
manual page for a for more information.

.PP
On a kernel with FIPS mode enabled, staprun normally refuses to attempt to
load systemtap-generated kernel modules.  This is because on some kernels,
this results in a panic.  If your kernel includes corrections such as
linux commit #002c77a48b47, then you can force staprun to attempt module
loads anyway, by setting the
.BR STAP\_FIPS\_OVERRIDE
environment variable to any value.

.SH FILES
.TP
/lib/modules/VERSION/systemtap
If MODULE is a module name, the module will be looked for in this directory.
Users who are only in the
.I 'stapusr'
group can install modules
located in this directory.  This directory must be owned by the root
user and not be world writable.

.SH SEE ALSO
.IR stap (1),
.IR stapprobes (3stap),
.IR stap\-server (8),
.IR stapdyn (8),
.IR stapex (3stap)

.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR http://sourceware.org/systemtap/ ", " <systemtap@sourceware.org> .
.hy

